Release 10.1A: OpenEdge Development:
ProDataSets

Passing a ProDataSet with APPEND

You can include the APPEND keyword in a ProDataSet OUTPUT parameter just as you can for a temp-table. For example:

RUN getMoreData.p [ ON SERVER hXYZ ] ( OUTPUT DATASET MyDSet APPEND ).

In this example, suppose that ProDataSet MyDSet is defined within the calling procedure and has already been filled with some amount of data, normally in a previous call to a procedure on server XYZ. In that previous call, not all the data that could be used was filled. The procedure on the server might have deactivated some of the relations in the ProDataSet in order not to fill all levels of detail (on instructions from the client, perhaps).

Based on some event on the client, such as the user selecting a particular parent record for which detail has not yet been filled, the client procedure runs getMoreData.p on the server with the same ProDataSet as an OUTPUT parameter along with possibly one or more additional parameters that indicate how the ProDataSet should be further filled. The server procedure fills that part of the ProDataSet the caller wants, perhaps by retrieving the parent record the user wanted more detail for, and then doing a FILL on that buffer, which would fill all its children. The server procedure then returns the ProDataSet to the caller.

The APPEND keyword tells Progress to append all the data passed back to the data that is already in the client’s ProDataSet. Duplicate rows will result in an error when the data is appended, and thus must be eliminated in advance, before making the call. This happens regardless of the setting of the FILL-MODE attribute on the ProDataSet’s buffers. The FILL-MODE thus applies only on FILL, not on parameter passing.

If you need to empty one or more of the receiving procedure’s temp-tables during this kind of operation, you can simply empty it before the call, rather than using the EMPTY FILL-MODE.

If you want to refresh records with later versions from the called procedure, you must empty the table or delete the selected records to be refreshed before making the call.

Another typical use case beyond filling in levels of detail not yet retrieved is to define a form of batching of data by requesting more records for one or more tables not yet completely filled.

For an exploration of batching and selective filling use cases, see Chapter 8, "Batching Data with ProDataSets,"), and Chapter 7, " Advanced Events and Attributes."